Gold Medal Software 3

home *** CD-ROM | disk | FTP | other *** search

/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / accounts / vndnfo10.arj / VENDEDIT.DOC < prev next >

Wrap

Text File | 1994-01-05 | 72.4 KB | 2,007 lines

+----------------------------------------+ | | | | | User's Guide | | | | VendEdit(TM) Editor | | for creating VENDINFO(TM) records | | Version 1.00 | | | | | | Last updated: December 1993 | | | | | | Copyright 1993 Rams' Island Software | | All rights reserved | | | +----------------------------------------+ Rams' Island Software 7644 E. Lakecliff Way _______ Parker, CO 80134-5904 (USA) ____|__ | (R) --| | |------------------- Voice: (303) 841-2848 | ____|__ | Association of BBS: (303) 841-6269 | | |_| Shareware CompuServe: 76244,324 |__| o | Professionals -----| | |--------------------- FidoNet: 1:104/333 |___|___| MEMBER RIME: RAMSISLE Internet: 76244.324@CompuServe.Com VendEdit User's Guide VendEdit +-----------------+ | Acknowledgments | +-----------------+ Many people have helped to mold the VENDINFO vision, and to provide support and encouragement throughout its development process. Thanks are given to all those who have reviewed the Concept Paper or the VENDINFO standard, or who have otherwise made suggestions regarding the project. The author is especially grateful to Fred Hill and Richard Holler, for long-term support and help with VENDINFO. While many have reviewed parts of the VENDINFO documentation, special thanks go to Jim Green, for helping us avoid a wrong direction; to Bob Ostrander for a simple but particularly powerful idea; and to Daan van Rooijen, for really studying the standard and providing many, many useful suggestions. Many people have also helped in beta testing the VENDINFO tools, and we're grateful to them all. Special thanks are given to Steve Estvanik and Jerry Stern, for really giving things a workout, and tirelessly reporting the results. The VENDINFO team is grateful to the following shareware trade associa- tions for their endorsements of VENDINFO: Association of Shareware Professionals (ASP) Association of Shareware Authors and Distributors (ASAD) Shareware Trade Association and Resources (STAR) Educational Software CoOperative (ESC) Finally, we particularly appreciate the 30-or-so software development teams (mostly BBS-related) whose early commitment to support the VEN- DINFO standard in their software products has helped provide momentum and visibility to this effort. VENDINFO, VendEdit, VendPrcs, VendView, and VendLib are trademarks of Rams' Island Software. VendEdit Editor v1.00 -ii- Dec 1993 VendEdit User's Guide Table of Contents +-------------------+ | Table of Contents | +-------------------+ The VENDINFO System ................................................ 1 Components of the System ........................................ 1 Structure of a VENDINFO File .................................... 2 A Little Background ............................................. 3 Industry Support and Endorsements ............................... 4 Other VENDINFO Documents and Packages ........................... 5 Installation ....................................................... 6 Quick Start ..................................................... 6 Detailed Contents of the VendEdit Package ....................... 7 Special Tips for the Inexperienced Shareware Author ............. 9 Warranty and License ............................................ 9 Technical Support for VendEdit .................................. 9 Overview of the VendEdit Process ................................... 11 Making a VENDINFO Intermediate File ................................ 13 Prepare Text Materials .......................................... 13 Packaging Directory(s) .......................................... 14 Invoke VendEdit ................................................. 15 Edit a New File ................................................. 15 Edit Author/Publisher Information ............................... 16 Edit Product Information ........................................ 16 Edit Order Information .......................................... 17 Edit Distributor Information .................................... 17 Edit Support Information ........................................ 18 Edit Price/Benefit Information .................................. 18 Edit General (Channel-Independent) Distribution Policy .......... 18 Edit Channel-Specific Distribution Policy ....................... 19 Edit Front Text ................................................. 19 Verifying the Intermediate File .................................... 20 Exporting VENDINFO.DIZ and Other Files ............................. 21 Checking the Results ............................................... 22 The VENDINFO Product Registry ...................................... 23 A Bit of Philosophy ................................................ 25 Philosophy Regarding Distribution Restrictions .................. 25 Algorithm Used for Distribution Permission Tests ................ 26 Legal Matters ................................................... 27 VendEdit Editor v1.00 -iii- Dec 1993 VendEdit User's Guide Table of Contents Security ........................................................... 29 VendEdit Editor v1.00 -iv- Dec 1993 VendEdit User's Guide Introduction to VENDINFO +---------------------+ | The VENDINFO System | +---------------------+ VENDINFO is a system for conveying software product information and distribution permissions from the author to distributors. A standard (public) file format allows a VENDINFO.DIZ file to carry extensive information in a compressed, efficient form. The associated toolset aids the author in constructing the record, and allows the dis- tributor to extract portions of the record, or to make distribution decisions based on its content, in a highly automated way. VENDINFO provides unprecedented capabilities for o Communication of product information and distribution policies from author to distributor. o Automation of many aspects of package handling by shareware distributors of all types. Components of the System ------------------------ The VENDINFO "record" is the key. This is an efficiently compressed file (VENDINFO.DIZ) containing a great deal of information about the product, the author, and the product's distribution policies. The VendEdit editor allows the author to construct a complete VENDINFO record in just a few minutes, assuming that the necessary descriptive texts have already been prepared. The VendPrcs (pronounced "vend process") processor is a batch program allowing automated decisions based on VENDINFO content, and automated extraction of VENDINFO information. VendView is a simple viewer allowing the end-user to see relevant portions of the VENDINFO data. This program should be available by February 1994. Even without VendView, an ordinary text viewer will display a good deal of useful information. The Product Registry is a collection of VENDINFO records available for searches and queries by subscription, BBS login, or mail-order query. This service will begin in January 1994. The VendLib Library allows software developers to build VENDINFO access directly into such products as BBS programs and upload proces- VendEdit Editor v1.00 -1- Dec 1993 VendEdit User's Guide Introduction to VENDINFO sors. This library is already in the hands of some 30 vendors of BBSes, BBS utility software, and other relevant software. The file-format standard describing the VENDINFO file is public, and draft versions have been published since July 1993. The final version 1.00 has been released, and is the basis for the current toolset. VendPrcs Plus, a non-shareware version of VendPrcs, is planned for release by Spring 1994. It will have a full-screen interface, using scripts for easier, more efficient information extraction, and templates for easier description of decision situations. It will also allow management of a library of VENDINFO files, and will provide automated access to the Product Registry BBS. Additional services for authors, users, and distributors are under consideration. Structure of a VENDINFO File ---------------------------- The VENDINFO.DIZ file contains two sections. A human-readable front section contains information about how to use the VENDINFO file, and presents most of the basic information about the product in readable form. The second section is a binary data record, compressed with a PKZIP 1.10 algorithm, and appended to the file after the first section. This record has some 750 fields of information about such things as o Product name, date, and version o Preferred package filename, other parts of product, replaced versions o Product descriptions of varying length, categories, keywords o Required platform (CPU, operating system, memory, disk, features) o Contact information for author, for registering, for tech support o Registration prices and benefits, acceptable forms of payment o Warranty and trial-use license o Detailed distribution policy, in general and by distribution channel VendEdit Editor v1.00 -2- Dec 1993 VendEdit User's Guide Introduction to VENDINFO o Information about regional distributors and registration services. A Little Background ------------------- The author of the VENDINFO standard and tools, Rudy Ramsey, has been agitating since early 1992 for the development of an improved mechanism for conveying product information and permissions from authors to distributors. Initially, the intent was to make this a purely volunteer-based effort, probably conducted within the auspices of the Association of Shareware Professionals. However, others were slow to respond to the idea (with the exception of Richard Holler and Fred Hill), and it gradually became clear that it would have to be done as an "extracurricular" effort, if at all. In the Spring of 1993, Rudy began the VENDINFO effort in earnest, by preparing the CONCEPT.DOC concept paper and distributing it to a few key shareware industry figures for comment. (At this time, he still imagined VENDINFO as an all-volunteer effort.) The reviewers were uniformly excited about the idea, and greatly encouraging. Most felt that it was an idea whose time had come, and that the technical approach described in the concept paper was very appropriate. Their second response, however, was that the effort contained the seeds of its own failure. It might provide all the necessary incen- tives for participation by authors, distributors, and users. But if it didn't also provide an incentive for continued development and support by its own development team, it would fail. It was simply too big an activity for successful execution by volunteers. As a result of that input, a decision was made to regard VENDINFO as partly a business opportunity. Although this makes a few people suspicious, most agree it's in the best interest of the VENDINFO effort itself, and of the industry. In fact, VENDINFO has developed rapidly, partly because it has been a full-time focus of its author for many months. That wouldn't have been possible in an all-volunteer effort. The VENDINFO file-format standard is public. A substantial period was provided for public comment on the concept paper, and then on the standard, and public input is always welcome. Some of the tools that make use of the standard are free (a viewer for end users, and the processor when used by single-line, noncommercial BBSes). Most are low-cost shareware. There will also be much-enhanced, non-shareware programs later, for special purposes, but none of them are necessary to achieve the benefits of the VENDINFO system. VendEdit Editor v1.00 -3- Dec 1993 VendEdit User's Guide Introduction to VENDINFO Industry Support and Endorsements --------------------------------- Support for the VENDINFO concept has been extraordinarily high throughout the industry. Authors, disk vendors, CD-ROM publishers, Sysops, and BBS software manufacturers have all expressed their support, and many have pledged to build VENDINFO capability into their own software products. The following shareware trade groups have formally endorsed the VENDINFO file-format standard as a means of conveying product and product-distribution information from authors to users and dis- tributors. Association of Shareware Professionals (ASP) Shareware Trade Association and Resources (STAR) Association of Shareware Authors and Developers (ASAD) Educational Software CoOperative (ESC) The ASP has licensed the VENDINFO toolset for use by all 1700 of its members. This will greatly accelerate the use -- and the usefulness -- of VENDINFO. The following software manufacturers have "committed in principle" to support VENDINFO in their own software offerrings by mid-1994. In the context of these products, "support" for VENDINFO means extracting relevant descriptive information automatically from VENDINFO files. It does not necessarily mean making decisions based on the product's distribution policy. VendPrcs will provide that capability. BBSes PCBoard, Clark Development Co. Wildcat!, Mustang Software, Inc. Major BBS, Galacticomm RBBS, RBBS Development Team Searchlight BBS, Searchlight Software TBBS, eSoft Auntie BBS, Wes Meier Executive Host BBS, Steve Wood MainLine BBS, Scott Green, City Limits Software OmegaComm BBS, Larry Loiselle PowerBBS for Windows, Russell Frey ProBoard BBS, Philippe Leybaert Sapphire BBS, Pinnacle Software Tinyhost, Bruce Krobusek UltraBBS, UltraBBS Software Windowed Modem Environment, Jason Fesler VendEdit Editor v1.00 -4- Dec 1993 VendEdit User's Guide Introduction to VENDINFO File Upload Processors CatScan, Mike Ortiz CheckZip, Bill Hull DIZIT, Robert Neal/CorpSoft HoboScan, Floyd Hobson TransScan, Craig Dunstan File Distribution Processors WCFF, Online Computer Resources Other Products *BBSee Disk Cataloger, Martin Vallevand *Catalog-on-a-Disk, EmmaSoft Software Company, Inc. Colorado Utilities Disk Manager, Micro Systems Solutions SmartCat Disk Cataloger, Oakley Data Services * Test versions are known to exist which support VENDINFO Other VENDINFO Documents and Packages ------------------------------------- The VENDINFO idea is documented in a concept paper and in the VEN- DINFO file-format standard. These two documents are available in the VENDINFO package, usually named VNDINFxx.ZIP. It can be obtained from the Rams' Island BBS on first login or by FidoNet or RIME file re- quest (magic name VENDINFO). It is also available in the CompuServe SHAREWARE and UKSHARE forums; the ASP Hub Network BBSes, many local BBSes, from some disk vendors, and on the ASP CD-ROM. If necessary, the concept paper and evaluation versions of the basic toolset can be obtained on diskette from Rams' Island Software for US$ 8.00 plus $2.00 shipping and handling in North America, $4.00 elsewhere (starting January 1994). Payment is accepted by Visa/MasterCard, check in U.S. dollars drawn on a U.S. bank, cash in any hard currency (registered mail suggested), and various other forms. An article about the VENDINFO system will appear in the November/December 1993 issue of Shareware Magazine. VendEdit Editor v1.00 -5- Dec 1993 VendEdit User's Guide Installation +--------------+ | Installation | +--------------+ To install the VENDINFO Basic Toolset, simply unzip or copy all files into a single directory, which will be devoted to VendEdit. If you are an author, or you expect to create VENDINFO records for testing purposes, you should plan to leave all these files in that directory. If you are a distributor, and plan to use only VendPrcs, then it will eventually be appropriate for you to place VENDPRCS.EXE on your path, and many of these materials will not be needed after your familiarization with the toolset is complete. Once you've installed this package: o If you're an author, or wish to try out VendEdit, simply execute the command "VENDEDIT" WHILE IN THE VendEdit DIRECTORY. Select "Help", and read through the first few items in the help index. You should find all the information you need. o If you're a distributor, or wish to try out VendPrcs, you should begin by reading VENDPRCS.DOC. For authors, the basic VendPrcs functions are executed automatically from VendEdit. Quick Start ----------- If you want to try using VendEdit with the absolute minimum of in- struction it is suggested that you read the following chapters of this User Guide Introduction to VENDINFO (earlier in this user guide) Overall Process of Using VendEdit (later in this user guide) Alternatively, you can read the corresponding sections of the VendEdit help text. Just go to the VendEdit directory, invoke VENDEDIT.EXE, and press Alt-H for the help system index. You can then place the cursor on the section you want to read, and press ENTER. VendEdit Editor v1.00 -6- Dec 1993 VendEdit User's Guide Installation Once you've read this introductory material, simply invoke VENDEDIT and follow this simple instruction: ───────────────────────────────────────────────────┐ │ Work your way left-to-right, and top-to-bottom, │ │ through the VendEdit menu structure. │ └───────────────────────────────────────────────────┘ You should be prepared to make extensive use of the context-sensitive help that's available throughout VendEdit. Even the menu items that only lead to other menu items have useful help text. Just press F1. Detailed Contents of the VendEdit Package ----------------------------------------- The VENDINFO toolset package includes the following files that are specifically relevant to the VendEdit editor: VENDEDIT.DOC This document. REGISTER.FRM Registration form for VendEdit, and several other products and services associated with the VENDINFO system. VENDEDIT.EXE The executable program for VendEdit. VENDEDIT.HLP Help file used by VendEdit. STATUS.DAT A text file used by VendEdit for status messages. VERIFY.DAT A text file used by VendEdit for testing the infor- mation you provide in your VENDINFO file. VENDPACK.EXE A small compression program used by VendEdit. CATEGORY.INF Product category data file used by VendEdit and VendPrcs. EXTRACT.BAT A batch file used for extracting all fields from a VENDINFO.DIZ record. This batch file is invoked automatically by VendEdit's <T>est <C>ontents command, but may also be used separately. EXTRDIST.BAT A batch file used for extracting distribution policy information for a single channel from a VENDINFO.DIZ file. This batch file is called from EXTRACT.BAT. VendEdit Editor v1.00 -7- Dec 1993 VendEdit User's Guide Installation EXTRREGL.BAT A batch file used for extracting information about distributors of your registered version. This batch file is called from EXTRACT.BAT. TESTDIST.BAT A batch file used to perform a variety of distribu- tion policy tests on a VENDINFO.DIZ file. This batch file is invoked automatically by VendEdit's <T>est <P>olicy command, but may also be used separately. It also includes these files, which are relevant to the VendPrcs processor, which distributors will use to access information from your VENDINFO.DIZ files: VENDPRCS.EXE The VendPrcs program itself. VENDPRCS.DOC The VendPrcs User Guide. VPRESULT.CFG A sample of the configuration file used to control part of the VendPrcs behavior. EXAMPLES.ZIP A PKZIP-compressed file containing samples of other batch files that can be used with VendPrcs, sample VENDINFO.DIZ files, and the corresponding printouts of their content. Finally, the package contains these files, which describe the entire VENDINFO toolset package: VENDINFO.DIZ The VENDINFO.DIZ file that describes this whole VENDINFO toolset package. As a further introduc- tion, it's worth viewing with a text viewer. FILE_ID.DIZ A small file containing a description of this package, currently used by many BBS and BBS-utility programs to automatically load such descriptions into their files databases. VENDINFO will even- tually render this convention obsolete, but FILE_ID.DIZ files should continue to be used, for now. VENDOR.DOC A small "stub" pointing the distributor to VENDINFO.DIZ for information. READ_ME.1ST A small "stub" pointing the user to VENDINFO.DIZ for information. VendEdit Editor v1.00 -8- Dec 1993 VendEdit User's Guide Installation Special Tips for the Inexperienced Shareware Author --------------------------------------------------- Aside from its ability to produce VENDINFO records, the VendEdit editor can be a serious educational tool for the beginning shareware author. Both the VENDINFO record and the VendEdit help text contain a wealth of information about the description and distribution of shareware. To take full advantage of this capability, it is suggested that you read all the material in the help system, either by select- ing Help and working your way through the index, or (perhaps better) by working your way sequentially through the menu system, pressing F1 everywhere. Even the menu items, such as Edit and Verify, that only lead to other menu items have useful help text associated with them. Warranty and License -------------------- VendEdit and VendPrcs are shareware products, which you may fully evaluate before deciding whether or not you wish to purchase them. The Warranty and License governing your use of these products will be found in the VENDINFO.DIZ file (read it or print it with the tools you use for ordinary text files). Or, if you prefer, you'll find these materials in the VendEdit help system. Technical Support for VendEdit ------------------------------ If you have a problem with installation or use of this product, and the documentation doesn't provide the help you need, you are welcome to contact us. You can do this in any of several ways. RAMS' ISLAND BBS The Rams' Island BBS is a bulletin board system, accessible to you if if you have a modem and communication software. On our BBS, you will always find the latest version of the program, and you will be able to ask technical questions of us and of our other users. We also offer additional utilities, class definitions, application notes, and other assistance to registered users via the BBS. The BBS phone number is 303-841-6269. COMPUSERVE INFORMATION SYSTEM We also support this product on the CompuServe information system. The latest version of the program is always available there in the SHAREWARE and UKSHARE forums, and technical questions and support requests may be sent to us via electronic mail there or on the VendEdit Editor v1.00 -9- Dec 1993 VendEdit User's Guide Installation CompuServe SHAREWARE and UKSHARE forums. Our CompuServe user ID is 76244,324. BBS NETWORK FORUMS We have established VENDINFO support forums on both the FidoNet and RIME networks. We are investigating a VENDINFO forum on GlobalNet. OTHER ELECTRONIC ADDRESSES You can reach us through three other computer networks (you can usually find a local BBS that's also on these networks). Our FidoNet address is 1:104/333. Our RIME address is 1235 or RAMSISLE. Our Internet address is 76244.324@compuserve.com. VOICE TELEPHONE You may reach us by voice telephone at 303-841-2848. MAIL You may contact us by mail at Rams' Island Software 7644 E. Lakecliff Way Parker, Colorado 80134-5904 USA VendEdit Editor v1.00 -10- Dec 1993 VendEdit User's Guide Overall Process +----------------------------------+ | Overview of the VendEdit Process | +----------------------------------+ Here's the short form of the instructions for using VendEdit to prepare a VENDINFO-equipped package: ───────────────────────────────────────────────────┐ │ Work your way left-to-right, and top-to-bottom, │ │ through the VendEdit menu structure. │ └───────────────────────────────────────────────────┘ Here's a more detailed description of the procedure: o If text materials already exist which you would like to use in product descriptions, or in the Read-Me, Installation, War- ranty, License, etc., use a normal text editor to prepare *.TXT files containing these materials. This will work best if you use a separate file for each of these, and a separate file for each product description. o Use VendEdit to prepare the VENDINFO information for the product. The simplest approach is to work left-to-right and top-to-bottom through the entire VendEdit menu structure, from <P>repare through <V>erify. The additional menu items, e<X>port and <T>est, will be discussed separately below. o Assign a directory for "packaging" the product. Place the files that make up the package in this directory. If the product involves multiple packages (e.g., multiple diskettes or ZIPs), each package should have its own directory. In this case, the package directories must be subdirectories within a common directory. In any case, each package directory must have the package name that will be associated with the released ZIP (e.g., the files that make up INCXT11A.ZIP will be in the INCXT11A subdirectory). This step can be done sooner, but, in any case, it must be done before an actual VENDINFO.DIZ file can be prepared. o Now start down the items in the e<X>port menu. First, select <S>etup to start preparation of the final package. You will tell VendEdit where the package directories are, and whether or not you want a standard date/time stamp on files that are created by VendEdit. You can also look over the files in the package from here. o The next several items in the e<X>port menu are optional files that you might or might not want to include in the package. You VendEdit Editor v1.00 -11- Dec 1993 VendEdit User's Guide Overall Process may direct VendEdit to produce FILE_ID.DIZ and DESC.SDI files (we recommend the former, for sure). Since the VENDINFO.DIZ file will contain Read-Me and Vendor.Doc style information, you may want to point unfamiliar users and vendors to VENDINFO.DIZ. For this purpose, VendEdit will product small "stub" files READ_ME.1ST and VENDOR.DOC or VENDOR.TXT, which simply refer the user to VENDINFO.DIZ. Finally, you may produce a small READ_ME.BAT file, if you wish, which will invoke the DOS "more" command on VENDINFO.DIZ to allow the novice user to easily read the VENDINFO front text. o At this point (proceeding down the items on the e<X>port menu), you'll be given a chance to check the package. You must get the files in their FINAL CONDITION before producing VENDINFO.DIZ files. That's because the VENDINFO.DIZ file contains a Packing List, which can be checked against the package actually received by your distributor. If any file differs in name, size, date, time, or CRC from those present when you created the VENDINFO file, your package might be rejected. o Export the VENDINFO.DIZ file. o Perform the operations on the <T>est menu, to verify that the VENDINFO file you created says what you think it does. THIS IS VERY IMPORTANT! Your distribution package is now ready. When you release your product, you'll also want to send a copy of the VENDINFO.DIZ file to our Product Registry. That will make it avail- able to many distributors and end-users who may otherwise not know about your product, and it can even generate income for you (see the chapter, "The VENDINFO Product Registry" for details). VendEdit Editor v1.00 -12- Dec 1993 VendEdit User's Guide Making Intermediate File +-------------------------------------+ | Making a VENDINFO Intermediate File | +-------------------------------------+ Prepare Text Materials ---------------------- VendEdit has the ability to import existing text files into several areas: o Product descriptions o Read-Me text o Installation instructions o "Other" author material for readable front text o Product warranty o License for use and distribution If you're preparing a VENDINFO record for a product that has already been released, you almost certainly have this text written. Even if your product is new, you may find it more convenient to prepare this material with your preferred text editor, and then import it into VendEdit. On the other hand, the text editor inside VendEdit is rather capable, so you certainly don't have to do it this way. If you decide to prepare the text files before using VendEdit, it is suggested that you prepare several different files, using any desired filename and the filename extension TXT. These files can be placed anywhere, but they will be most easily found if they're placed in the VendEdit directory. Possible filenames, with their purposes, are: DESC250.TXT Product description of not more than 250 bytes DESC450.TXT Product description of 450 bytes (FILE_ID.DIZ size) DESC750.TXT Product description of not more than 750 bytes DESC1500.TXT Product description of not more than 1500 bytes READ_ME.TXT "Read-Me" text for front of VENDINFO.DIZ INSTALL.TXT Installation instructions WARRANTY.TXT Product warranty LICENSE.TXT License for use and distribution, but note that there are special requirements for the Distribution License in a VENDINFO file. OTHER.TXT Other text sections which the author wants in the VENDINFO front text. VendEdit Editor v1.00 -13- Dec 1993 VendEdit User's Guide Making Intermediate File There are some minor format constraints: o The product descriptions should use a block paragraph structure (no indentation, one blank line between paragraphs). It must use no special formatting (tables, lists that must align like the text you're now reading, boxes around text, etc.). This is because it will be extracted with word-wrapping, and refor- matted using automated tools by the distributor. o It also must contain no high-ASCII or special low-ASCII charac- ters (all the characters on a normal keyboard are acceptable). This is because it will be printed in catalogs, entered in databases, etc., and such characters are useless or even damag- ing in such situations. If a file containing such characters is read in, all "illegal" characters will be converted to "*", but you may find that less satisfactory than converting such text yourself. o The "front text" files ("Read-Me", etc.) should be no wider than 73 characters, but they do not have the formatting or character-set limitations of the product descriptions. If you import a text file wider than 73 characters, be sure to refor- mat each paragraph to the proper width (F5 will do a simple paragraph reformat automatically for you). When you have prepared these files, or decided not to, you're ready to <E>dit your first VENDINFO file. Packaging Directory(s) ---------------------- There is one other preparation step you should be aware of, though it isn't necessary that it be done before preparing the VENDINFO inter- mediate record. That step is preparation of the directory(s) for your distribution package(s). Before VendEdit can actually produce a VENDINFO.DIZ file, it will need access to a directory containing all the files in your distribution package. Among other things the VEN- DINFO file contains a Packing List that has filenames, sizes, dates, and CRCs for all the files in your package. VendEdit makes two as- sumptions about these distribution package directory(s): o It is assumed that the files for a given package are in a directory whose name is the prefix of the package name that will be used. For example, the first package of InContext is INCXT11A.ZIP. The files that make up this package are in the directory INCXT11A. VendEdit Editor v1.00 -14- Dec 1993 VendEdit User's Guide Making Intermediate File o If there are multiple packages for the product, it is assumed that their package directories are all subdirectories of the same directory. You might save a little time if you plan your product package con- struction in this way. It is perfectly acceptable to place these package directories under the VendEdit directory, though you may find it preferable to keep things organized by product. After you have entered the information that VendEdit requires about your product, you'll reach an e<X>port <S>etup menu in which you'll specify the directory under which you've placed the package directories. Invoke VendEdit --------------- To invoke VendEdit, simply go to the directory in which you've in- stalled the VENDINFO toolset, and execute the command vendedit Once you've created a VendEdit intermediate file for your product, you can invoke VendEdit on it from the command line, by adding the filename to the command. For example, vendedit INCXT11.PRD Edit a New File --------------- When you begin editing a new VENDINFO intermediate record, you'll be asked to provide a few basic pieces of information which VendEdit can use to automatically fill in a number of fields in the VENDINFO record. You'll save yourself work if you provide this information carefully, but ALL of it is still subject to change later, if neces- sary (use the <E>dit <P>roduct command). In particular, you'll be asked to decide upon file naming conventions for your distribution packages, using some standard conventions. One possibility, for example, is that you'll distribute your product as a compressed file named MYPROD10.ZIP, where "MYPROD" is probably a portion of your product name, and "10" represents version number 1.00. You are not required to use the standard file naming conven- tions, but they are very helpful to distributors, and are strongly recommended. Once you're in the "Edit a New Record" data-entry screen, use the help system to access more detailed, and highly relevant, informa- VendEdit Editor v1.00 -15- Dec 1993 VendEdit User's Guide Making Intermediate File tion. To see field-relevant help information, just press F1, the "Help" key. You'll be shown help information that's relevent to the field the cursor was on as you pressed F1. Edit Author/Publisher Information --------------------------------- This section of the VENDINFO record identifies the author/publisher and allows very complete contact information to be provided, if desired. Trade association memberships are also noted here. This section should be completed first, and in a single session. The contact information will be copied automatically into the "Orders" and "Support" sections as you exit the Author section. While this may occasionally be unhelpful, it will usually save a good deal of work, since these three sections usually contain much the same information. The trade association information also affects default product descriptions in the "Product" section. The bold exclamation point symbols ("!") on the display call your attention to particularly important help information. There is useful help information associated with virtually every field, but those marked with the "!" symbol should be read even if you skip the others. The "Company Name" and "Queries" (phone) fields have special sig- nificance, and are mandatory (see the help text). Once you have created your first VENDINFO file, you need not enter the Author information again. The F4 (import) key can read a whole "Author" section from an existing file. Edit Product Information ------------------------ This section will describe your product in various ways. You will provide information about the product name and version, and filename information for the compressed package(s) in which you distribute it. You will construct (or read from existing text files) product descriptions of various lengths, and select descriptive categories and keywords. The product name, version, and filename information is important to the correct behavior of the VENDINFO tools. Please provide this information carefully, with special attention to the help text as- sociated with the fields marked with an "!". VendEdit Editor v1.00 -16- Dec 1993 VendEdit User's Guide Making Intermediate File A special section of the Product information is devoted to the Plat- form needs of your product. Here, you can indicate the basic type of computer required, and both minimal and recommended levels of CPU, operating system, memory, clock speed, etc. You can also indicate which of a long list of system features are relevant to your product. Edit Order Information ---------------------- This section of the VENDINFO record contains contact information to enable users to purchase the registered version and other products and services. It also indicates the various forms of payment you accept, and other sources of registered versions, if any. The contact portion of this section is very similar in structure to the Author section, though the content you provide may differ. If you edited the Author section first, the Order section will initially contain information from there. Once you have created your first VENDINFO file, you need not enter the Order information again. From within the Order section, the F4 (import) key can read a whole "Order" section from an existing VENDINFO file. Edit Distributor Information ---------------------------- Within the Orders section, there is an "Other Distributors of Regis- tered Version" area. Many authors will make no use of that area. However, if you have distributors who handle registrations for you -- either world-wide or in specified geographical areas -- you will want to list them there. This will help users in their region -- and journalists and other distributors, if appropriate -- to get in contact with them. The help text for that section contains more detailed information. One special capability is worth noting. Distributors can use VendEdit to prepare information about themselves in the form of a *.DST file. You can then import the contents of such a file into your VENDINFO file using the F4 key. This allows you to provide your users with good contact information for the distributor, and even information about credit cards and other acceptable forms of payment. See the help text for more information. VendEdit Editor v1.00 -17- Dec 1993 VendEdit User's Guide Making Intermediate File Edit Support Information ------------------------ This section of the VENDINFO record contains contact information to enable your users (and reviewers of your product, etc.) to obtain technical support. This section is very similar in structure to the Author section, though the content you provide may differ. If you edited the Author section first, the Support section will initially contain information from there. Once you have created your first VENDINFO file, you need not enter the Support information again. The F4 (import) key can read a whole "Support" section from an existing file. Edit Price/Benefit Information ------------------------------ This section contains information about registration prices and benefits (both a minimum and a maximum registration package can be described, if you have multiple packages). Shipping and handling charges are here, as is information about site licenses, dealer discounts, royalty requirements, and availability of alternative Non- Shareware Versions (NSVs) and Low-Cost Retail (LCR) versions. Edit General (Channel-Independent) Distribution Policy ------------------------------------------------------ In this section, you specify your distribution policy, to the extent that it is independent of specific distribution channels. You specify which basic distribution category it falls into: "Commercial" product, not distributable as shareware "Commercial" product, intended for distribution with other products Registered version, not distributable as shareware Registered version, intended for distribution with other products Shareware, subject to distribution restrictions Shareware, freely distributable by all channels Freeware, copyrighted but freely distributable and useable Demonstration product, freely distributable by all channels Public domain, freely distributable by all channels Retired product, removal from distribution requested Test version of product, not for further distribution You also specify what changes, if any, you allow to the outer com- pression wrapper and to the files in the package. You can also specify whether or not the distributor is allowed to bundle this product with others, and distribute the bundle. VendEdit Editor v1.00 -18- Dec 1993 VendEdit User's Guide Making Intermediate File You can provide royalty information, if applicable, and indicate the availability of site licenses, dealer discounts, low-cost retail versions, and non-shareware versions. Edit Channel-Specific Distribution Policy ----------------------------------------- In this section, you specify your product's distribution policy for each of 13 distribution channels: Distribution to End User by BBS Distribution to BBSes by File-Distribution Network Distribution to End User by Mail-Order Disk Vendor Distribution to End User by CD-ROM Distribution to End User by Single-Site Rack Distribution to Seller by Rackware Distributor Distribution to End User in Book Enclosure Diskette Distribution to End User by Subscription Service Distribution to End User by Magazine "Cover" Disk Distribution to End User by TV/cable/satellite Broadcast Distribution to End User by 1-900-Type Phone Service Product Installation by Distributor on End User's Machine Distribution by Substantially Different Means Simply select the channels, one at a time, and fill in or adjust the fields that define your distribution policy. Frequent use of the F1 (Help) key can assist you with this. Edit Front Text --------------- The five front sections allow you to convey a great deal of informa- tion to the user or distributor even before he installs your product. The text of these sections is supplied by you. Before you start your own text for a section, though, it is recommended that you import the "suggested" text and at least read it for ideas. To import this text, just press F3. The License is especially important, and will be somewhat different under the VENDINFO system than your previous licenses have been. It is very important that you consult the help text before completing the text of this section. VendEdit Editor v1.00 -19- Dec 1993 VendEdit User's Guide Verifying Intermediate File +---------------------------------+ | Verifying the Intermediate File | +---------------------------------+ The <V>erify menu gives you access to the error-detection capability of VendEdit. Obviously, there are lots of errors the editor can't reasonably be expected to detect, but it can help you avoid certain common mistakes. The <V>erify menu allows you to test for "Errors only", "Warnings and above", or "Comments and above". Before you export a VENDINFO.DIZ file into your package, it is suggested that you use the "Comments" level, and satisfy yourself that the file is OK. VendEdit Editor v1.00 -20- Dec 1993 VendEdit User's Guide Exporting Files +----------------------------------------+ | Exporting VENDINFO.DIZ and Other Files | +----------------------------------------+ Once your VENDINFO information is complete, you can begin to export the various files the VendEdit can produce. It is suggested that you consider the e<X>port menu choices in order, top-to-bottom. The first step, <S>etup, allows you to tell VendEdit the location of your distribution package(s). Be sure to consult the help text if you have any doubt about how this works. VendEdit currently expects your distribution files to be in a directory whose name matches the package filename prefix. Next, you can decide which, if any, of the optional exported files you want. We suggest FILE_ID.DIZ, READ_ME.1ST, and VENDOR.DOC, but you'll have to decide for yourself. Once those are done, you need to verify that your distribution package contains all the files you want it to have, and that they all have the desired date/time stamps if you care about those. The final export step is VENDINFO.DIZ itself, and it will contain a list of all the other files, each with name, size, date, time and CRC value. This will be used at the distributor end to check for changes, par- ticularly those that might violate your distribution license. Naturally, if *you* change a file after VENDINFO.DIZ is constructed, and don't rebuild the VENDINFO.DIZ file, your distributors will be told that the package has been altered. The processor can't tell who made the change. VendEdit Editor v1.00 -21- Dec 1993 VendEdit User's Guide Checking Results +----------------------+ | Checking the Results | +----------------------+ The <T>est menu allows you to perform three separate tests on the VENDINFO.DIZ file you've generated: o Visually inspect the readable front text of the VENDINFO.DIZ file, as it will be seen by users and distributors. o Use the VendPrcs distributor's tool to extract all the infor- mation from the data record into a readable file, and display it. o Use the VendPrcs distributor's tool to perform a variety of distribution-policy tests, and display the results as they would be seen by a distributor. These tests are VERY IMPORTANT! The VENDINFO file will be the first thing many users and distributors will see about your product. You will also be conveying legally binding distribution rights via the data record. You have a strong interest in making sure it's correct. Once you've done this, your distribution package is complete and ready to be compressed or copied to diskette. Remember to use the correct filename for the compressed package. VendEdit Editor v1.00 -22- Dec 1993 VendEdit User's Guide Product Registry +-------------------------------+ | The VENDINFO Product Registry | +-------------------------------+ The Product Registry is a service that accepts VENDINFO.DIZ files from authors and makes them available to distributors and even end users. There is no charge to the author for this service, and under some circumstances it can even generate a small amount of income for you. Distributors can pay to subscribe to the entire Product Registry collection, either by monthly mailing or by access to the Product Registry BBS. On-line and mail-order queries will be possible by Spring 1994. We can imagine users looking for a particular type of product by category and machine configuration. Or distributors look- ing for business programs they don't have, and which allow distribu- tion by their particular preferred method. In many cases, queries will be paid for on a charge-per-hit basis. One-third of the revenues from such hit charges will be paid to the authors whose products are "hit", so this can not only cause your product to be noticed, but it can even generate a little income for you. No special arrangements are necessary for this payment to occur. It will be paid quarterly; no payments will ever be made until your balance exceeds $15. We're trying hard to make the Product Registry work for everyone. We hope you'll support it by sending us your VENDINFO files. Please send only the MAIN VENDINFO.DIZ file for each product version. If you product has multiple packages, this is the VENDINFO file from the first package. DO NOT send your whole package -- it will be rejected. If you're sending VENDINFO files for more than one product, please rename them using the product filename prefix and the filename exten- sion "DIZ" (e.g., INCXT11.DIZ). VENDINFO files can be uploaded directly to our BBS (the preferred method), mailed on diskette, or sent by CompuServe e-mail or FidoNet crash mail. If you're sending them electronically, please compress them using PKZIP or LHA. Please add your Product Registry key (one of the registration codes you were given when you registered VendEdit) to the cover message to assure us that you're the sender. Our electronic and mail addresses are on the front cover of this manual. On an experimental basis, we are also going to try to maintain a collection of screenshots of your products. This will provide a VendEdit Editor v1.00 -23- Dec 1993 VendEdit User's Guide Product Registry useful service for distributors and journalists who may need shots of your products for catalogs, articles, or perhaps even BBS displays. A screenshot might also help distributors or even end users to decide whether or not to seek out your product. Whether or not we continue this service will depend on its popularity with distributors. We have a fair amount of disk space, however, and should be able to give it a fair test before we decide. If you want to submit screenshots, here's the procedure. You may submit up to three screenshots in each of two graphical formats. Prepare a separate ZIP file (use PKZIP) for each format. Place in it only the screenshots for that format, along with a FILE_ID.DIZ in- dicating what the files are, and identifying your product by name, version, and release date. Rename the ZIP file in the following way. For the filename prefix, use your product filename prefix. For the filename extension, use the filename extension associated with the graphical file format contained in the ZIP, then substitute the letter "Z" for the first character. Thus, INCXT11.ZIF would be a ZIP file containing GIF screenshots for the product "INCXT11". If you're sending screenshots, you must mail them on diskette. They will not be accepted by CompuServe e-mail, as the cost is prohibitive. Distributors are also asked to submit *.DST files for use by their authors. This will make it easy for all your authors to include very detailed information about you with very little effort, so it's in your interest to make these available. You may use an unregistered version of VendEdit to produce these, and they may be sent by any of the methods useable for VENDINFO.DIZ files. VendEdit Editor v1.00 -24- Dec 1993 VendEdit User's Guide A Bit of Philosophy +---------------------+ | A Bit of Philosophy | +---------------------+ Philosophy Regarding Distribution Restrictions ---------------------------------------------- Both authors and distributors will make more effective use of the VENDINFO system if they understand the point of view from which the system was designed. That point of view is outlined below. Regarding distribution restrictions by author/publishers: o The author should be able to express any possible distribu- tion restrictions, regardless of whether or not such restric- tions are well-advised. o Common and/or reasonable restrictions should be encoded in the VENDINFO record in such a way that automated tools can deal with them. o Other distribution restrictions should be expressible in text form, even if their presence will force conscientious dis- tributors to handle the package manually. o None of this should be taken as an encouragement for authors to impose distribution restrictions. In many cases, the documentation and help text of the VendEdit editor explicitly discourage restrictions. As an example, the author is advised to consider carefully before imposing ANY restriction on BBS distribution. o Authors will especially be warned against unnecessary use of options that force manual handling by distributors. Regarding testing for distribution permission: o In general, a proposed distribution is assumed to be NOT allowed until the distributor clearly addresses each condi- tion required by a product's distribution policy. This isn't done to constrain distribution or to make life difficult for distributors. It is done to protect all parties from acci- dents, misunderstanding, and even legal liability. Thus, if a product can be distributed by a disk vendor only if the per- disk charge is less than $10, VendPrcs will not "OK" the distribution because the vendor fails to mention the amount VendEdit Editor v1.00 -25- Dec 1993 VendEdit User's Guide A Bit of Philosophy charged. Algorithm Used for Distribution Permission Tests ------------------------------------------------ Based on the information you provide on the VendPrcs command line, and the distribution policy specified in the VENDINFO file, VendPrcs determines whether or not your proposed distribution satisfies the author's requirements. To do this, VendPrcs looks at the author's policy for the particular distribution channel you've indicated, as well as the channel-independent ("general") distribution restrictions in the VENDINFO file. The actual decision process works as follows. (The important thing to understand is the last step, but you may find it useful to understand the whole decision process.) o If distribution via the proposed channel is prohibited, then "reject". o See if distributor is "qualified". The author might indicate that all distributors are qualified. If not, you must meet at least one of the author's qualification criteria to be in this set. Example criteria are: ASP member, non-profit user group, agreeing to "fully inform" your customers. o If distributor is "qualified", see if any specific behavior removes this "qualified" status, such as charging customers more than allowed. o Distributor is now either "qualified" or "disqualified". The meaning of this distinction is specified by the author. There are three possibilities: 1. Qualified may distribute without written permission. Disqualified may distribute only with written permission. 2. Qualified may distribute without written permission. Disqualified may not distribute at all. (Obviously, with the author's written permission, you can do anything you want; what the author is really telling you is that written permission won't be given.) 3. Qualified must still have written permission. Others may not distribute at all. o Based on your qualified/disqualified status, VendPrcs deter- mines whether or not you need written permission, and whether VendEdit Editor v1.00 -26- Dec 1993 VendEdit User's Guide A Bit of Philosophy or not your proposed distribution is prohibited. If written permission is required, VendPrcs determines whether or not you've obtained it; if not, this requirement is noted in the log and will affect the errorlevel returned by VendPrcs. o If the distribution is allowed, either with or without writ- ten permission, VendPrcs looks for any additional author- specified conditions you must satisfy, and determines from the command-line flags whether or not you've satisfied them. If any conditions remain unsatisfied (including conditions specified by the author in text form), they are noted in the log and will affect the errorlevel returned by VendPrcs. o Unless you've disabled VendPrcs testing of executables, all *.EXE, *.COM, *.DLL, *.LIB, etc. files in the package are scanned for VENDINFO records, and a similar decision process is applied to any that are found. This feature is used to detect registered-user versions and commercial and other software not intended for further distribution. (See the later section, "Testing for VENDINFO-Branded Executables". o VendPrcs now informs you by DOS errorlevel (and in the log- file) that: 1. Distribution is prohibited by the VENDINFO file. 2. Distribution is prohibited by some included executable. 3. Distribution is OK if you satisfy additional requirements. 4. Distribution is OK if you obtain written permission. 5. Distribution is OK if you obtain written permission AND satisfy additional requirements. 6. Distribution is approved as-is. Legal Matters ------------- The License Agreement for the VENDINFO toolset is a little more complicated than most, and it is important that you familiarize yourself with it. You'll find it in the VENDINFO.DIZ file that came with the toolset, as well as in the VendEdit help system. In addition to the normal functions of a license agreement, this one serves an important role in the VENDINFO system. By requiring dis- tributors to agree to a few simple conditions, it helps protect the rights of authors and the confidence with which authors can use the VENDINFO system. Similarly, authors must agree to a few conditions that help protect the distributor. Details are explained in the VendEdit Editor v1.00 -27- Dec 1993 VendEdit User's Guide Security license itself. VendEdit Editor v1.00 -28- Dec 1993 VendEdit User's Guide Security +----------+ | Security | +----------+ The security features of VENDINFO make no claim to be hack-proof, but they should be sufficient to: o Eliminate manual editing of VENDINFO records, which could do serious accidental or deliberate damage. o Eliminate casual hacking. o Require effort on the part of a serious hacker that exceeds any likely gain. Some of the security features in the initial release of VENDINFO are: o The structure, complexity, and internal checks associated with the VENDINFO record are such that it is difficult to produce without a specialized VENDINFO editor. o The editor cannot edit a distributed VENDINFO file. It produces such files from an intermediate file -- which the author keeps -- in a one-way operation. o Both the text and data portions of the VENDINFO records are checked for size and CRC. o VENDINFO records can contain two "authentication" keys that help verify the source and unaltered content of the record. o The editor will produce "authenticated" VENDINFO records only in the presence of an author-specific key that is not con- tained in the distributed VENDINFO record. Planned capabilities for a subsequent VENDINFO release include: o If the author chooses, an abbreviated VENDINFO record can be embedded in any or all executable programs. This insures that basic identification and distribution policy information is present and automatically testable even if the VENDINFO record is removed from the distribution package. o If the author chooses, the executable VENDINFO record can require the presence of a specific VENDINFO file (identified by a CRC-like value). This would allow automatic detection of the removal of the VENDINFO file from the distribution VendEdit Editor v1.00 -29- Dec 1993 VendEdit User's Guide Security package. It would also allow automatic detection of the substitution of a VENDINFO file in the distribution package even if the file itself passed all security checks. o If the author places the executable VENDINFO record inside his/her own protective CRC envelope, a complete understanding of the VENDINFO security scheme would not be enough to defeat it. A hacker would also have to defeat the author's own security layer. o A separate mechanism exists which allows a central site (the Product Registry) to verify the authenticity of a VENDINFO record based on private keys. o A provision for author tracking brands in the uncompressed front-text of the VENDINFO.DIZ file. These brands will be visible to a file viewer, easily accessible to the author's own software, and defended against modification by in- dividuals other than the author. VendEdit Editor v1.00 -30- Dec 1993